SftTree/OCX 7.0

Distributing SftTree/OCX

Softel vdm, Inc.

This section describes the preferred distribution method when shipping SftTree/OCX with your application. This method follows Microsoft's guidelines on ActiveX control distribution. While these guidelines are not enforced, it is highly recommended that they are followed as outlined here. This insures that your application can be safely installed and use SftTree/OCX even if another vendor has already installed an application which also uses SftTree/OCX.

SftTree/OCX is not supported on Windows 95, 98, ME or Windows NT 4.0. Supported platforms include Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, Windows 8, Windows 10 and their server editions.

Installing SftTree/OCX (for an Application)

When distributing SftTree/OCX with your application, only the following files can be distributed with your application royalty-free.  These files allow the use of the control with your application.  The design-time interface is no longer available once SftTree/OCX is shipped with your application. For additional information regarding distributing this control with your application, see the license agreement.

Required Files

Important: Redistributable files are located in the SftTree/OCX installation directory (\Program Files\Softelvdm\SftTree OCX 7.0\Redist).

These files must be shipped with your application if SftTree/OCX is used:

File Name

Target Folder

Description

SftTree_IX86_U_70.ocx

See Control Target Directory below

Required for 32-bit applications.  SftTree/OCX control.  When distributing a managed .NET application compiled for "Any CPU", the 32-bit and 64-bit control must be distributed.

SftTree_x64_U_70.ocx

See Control Target Directory below

Required for 64-bit applications.  SftTree/OCX control. When distributing a managed .NET application compiled for "Any CPU", the 32-bit and 64-bit controls must be distributed.

Softelvdm.OCXHelperV2.dll

See SftHelperComponent Target Directory below

Required for .NET 2.0 and above ONLY. This .NET component is required when distributing managed .NET applications. It is not used for other (unmanaged) languages, like VC++, VB6, etc. This file requires the .NET 2.0 runtime (or newer). If your application uses the 2.0 runtime (or newer), this file needs to be distributed with your application.

Softelvdm.OCXHelper.dll

See SftHelperComponent Target Directory below

Required for .NET 1.x ONLY. This .NET component is required when distributing a managed .NET applications which requires the .NET 1.x runtime. It is not used for other (unmanaged) languages, like VC++, VB6, etc. If your application uses the 1.x runtime, this file needs to be distributed with your application.

Softelvdm.NETHelper.dll

Application Folder

Required for .NET 4.0 and above ONLY - Applications compiled for "Any CPU" or "x86". This dll is required when distributing managed .NET applications. It is not used for other (unmanaged) languages, like VC++, VB6, etc. This file is required if your application uses the .NET 4.0 runtime or newer and is compiled for "Any CPU" or "x86". If your application is compiled for "Any CPU" you will need both Softelvdm.NETHelper.dll and Softelvdm.NETHelper_x64.dll. If your application uses the 2.0 runtime or is compiled for "x86", this file can optionally be distributed with your application, but it is not required.

Softelvdm.NETHelper_x64.dll

Application Folder

Required for .NET 4.0 and above ONLY - Applications compiled for "Any CPU" or "x64". This dll is required when distributing managed .NET applications. It is not used for other (unmanaged) languages, like VC++, VB6, etc. This file is required if your application uses the .NET 4.0 runtime or newer and is compiled for "Any CPU" or "x64". If your application is compiled for "Any CPU" you will need both Softelvdm.NETHelper.dll and Softelvdm.NETHelper_x64.dll. If your application uses the 2.0 runtime or is compiled for "x86", this file can optionally be distributed with your application, but it is not required.

Oleaut32.dll 

\Windows\System32 or
\Windows\SysWow64

Required. OLE support.  While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.

Olepro32.dll

\Windows\System32 or
\Windows\SysWow64

Required. OLE property and standard types support.  While normally present, the installation must insure that the current version is installed.  This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.

Stdole2.tlb

\Windows\System32 or
\Windows\SysWow64

Required. OLE support.  While normally present, the installation must insure that the current version is installed.  This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.

Asycfilt.dll

\Windows\System32 or
\Windows\SysWow64

Required. OLE support.  While normally present, the installation must insure that the current version is installed.  This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.

Comcat.dll

\Windows\System32 or
\Windows\SysWow64

Required. OLE support.  While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.

Regsvr32.exe

any

Optional. Control registration utility, for "manual" registration. Not needed with most commercial Setup creation tools.

GDI+ (Optional)

Certain features of the control require GDI+ support. This is available automatically on Windows XP and above. GDI+ is available as a redistributable for Windows 2000 from Microsoft (www.microsoft.com) as part of the Platform SDK (Windows XP and newer). Usually, it is sufficient to simply distribute the Dll gdiplus.dll in your application directory.

If GDI+ support is not available, the features are simply disabled and alternate presentation methods are used, if necessary.

Control Target Directory

Depending on the target operating systems, one of the following target directories can be chosen.

A) Windows\System(32)

Installing the ActiveX control into the Windows\System32 directory (or Windows\SysWOW64 for 32-bit controls on Windows x64) is possible on all supported Windows platforms.

The setup program you provide with your application should install the SftTree/OCX control SftTree_IX86_U_70.ocx into the Windows System32 directory.  The Windows System directory name can be found using the GetSystemDirectory API function.  All other files shown in the above tables also have to be installed into the Windows System32 directory.  On Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7, Windows Server 2008 (R2), Windows 8, Windows 10, it is usually named C:\Windows\System32 (or Windows\SysWow64 for 32-bit controls on Windows x64).

The control is installed into the Windows/System(32) directory and registered using proper versioning and reference counting of the OCX file (usually automatic, with most commercial installers).  

B) Application Directory

An ActiveX control can be installed in the application directory using DLL/COM redirection, which is available on Windows 2000, 98SE and better only. 

DLL/COM redirection is activated on an application-by-application basis by the presence of a ".local" file. The ".local" file is an empty file in the same directory as the application's .exe file, with the same name as the application's .exe file with ".local" appended to the end of the name. 

For example, to activate DLL/COM redirection for an application called "SampleApp.exe", create an empty file called "SampleApp.exe.local" in the same directory where SampleApp.exe is installed.

On Windows XP or better, "Registration-Free Activation" (see below) can be used, which eliminates the need for the ".local" file.

Once DLL/COM redirection is activated, whenever the application loads a DLL or an OCX, Windows looks first for the DLL or OCX in the directory where the application's .exe file is installed.  If a version of the DLL or OCX is found in the directory where the application's .exe file is installed, the application uses it regardless of any directory path specified in the application or the registry.  If a version of the DLL or OCX is not found in the directory where the application's .exe file is installed, the normal search path or server path is used.

Even if DLL/COM redirection is used, the control must be registered during installation (see "Registering SftTree/OCX" below).  The control must be installed into the Windows/System(32) directory and registered using proper versioning and reference counting of the OCX file (usually automatic, with most commercial installers).  In addition, a private copy in your application directory is always installed (but not registered), along with the application's ".local" file.

SftHelperComponent Target Directory

The SftHelperComponent (see "Using SftTree/OCX with .NET") is used by .NET applications. Earlier releases of SftTree/OCX required this component to be registered using Regasm.exe for COM Interop. This is no longer required. Simply copy the file Softelvdm.OCXHelperV2.dll (or Softelvdm.OCXHelper.dll) to one of the following locations. They are listed in the order they are searched.

Softelvdm.OCXHelperV2.dll:

Softelvdm.OCXHelper.dll:

The actual path (\Program Files or \Windows) may differ due to localization.

Version Control

The setup program should only install the SftTree/OCX files if the version number in the new files is higher than the files already installed.  Maintenance releases of the product are fully upward compatible and are guaranteed to have a newer version number.  New versions of the product will use new file names and new GUIDs so there will be no conflict between different (major) versions, such as 4.5, 5.0, 6.0 and 6.5.

Reference Counting

When installing DLLs or OCX files into a "shared" location, such as the Windows\System(32) or \Windows\SysWOW64 directory, proper reference counting must be performed, to insure that the file isn't uninstalled until all applications making use of the DLL or OCX have also been uninstalled.  Reference counting is generally available with most commercial installers.  The Windows Registry contains a count of all such shared files in the following Registry location:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs

Registering SftTree/OCX

Depending on the target operating systems, one of the following ActiveX/COM registration methods can be selected.

A) Windows Registry

Registering the ActiveX control in the Windows Registry is possible on all supported Windows platforms.

The setup program should register SftTree/OCX in the Windows registration database (Registry).  This can be done manually using Regsvr32.exe which is discouraged.  Many commercially available setup programs can register SftTree/OCX during the installation of your application. Please keep in mind that 64-bit versions of Windows have two versions of RegSvr32.exe. \Windows\System32\RegSvr32.exe is used to register 64-bit controls and \Windows\SysWOW64\RegSvr32.exe is used to register 32-bit controls. On Windows Vista and above, RegSvr32.exe must be run with elevated privileges as administrator.

SftTree/OCX is a self-registering ActiveX control.  By using the LoadLibrary Windows API function, the GetProcAddress API can be used to obtain the DllRegisterServer function. By calling this function, the SftTree/OCX control will register itself with the Windows registration database (Registry). Most commercially available setup programs have support for this built-in. Check the documentation of your setup application for information on how to install ActiveX controls. Please keep in mind that an application using the LoadLibrary API can only load the control of the same machine type, meaning a 32-bit application can only load and register 32-bit controls, a 64-bit application can only load 64-bit controls.

The following files need to be registered in this manner:


File Name

Description

SftTree_IX86_U_70.ocx

Required for 32-bit applications. SftTree/OCX control

SftTree_x64_U_70.ocx

Required for 64-bit applications. SftTree/OCX control

Comcat.dll

OLE support

Oleaut32.dll

OLE support

Olepro32.dll

OLE support

B) Registration-Free Activation

On Windows XP and better it is possible to deploy this ActiveX control using "Registration-Free Activation".  Registration-free activation allows distribution of the control without the requirement to register the ActiveX control in the Windows Registry (using REGSVR32 or a Setup application).  Registration-free activation is supported by the operating system, so the .NET run-time is not required for registration-free activation.

By using registration-free activation, true XCOPY deployment is possible.  Your application uses its own copy of the control.  Versioning, reference counting and registration of the control are completely eliminated and other installed versions of the control cannot interfere with your application.

By using an application manifest and copying the OCX file SftTree_IX86_U_70.ocx and/or SftTree_x64_U_70.ocx into your application directory, the ActiveX control is automatically registered when it is used the first time.  Your application manifest must include the comClass and typelib definitions shown below.  These insure that your application automatically registers the control and uses the control located in your application directory, regardless of any other controls or other versions of the same control already installed or in use.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly 
   xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> 
<assemblyIdentity version="1.0.0.0" processorArchitecture="x86" name="SoftelvdmInc.SftTree10.Sample.exe" type="win32" /> 
   <description>SftTree Sample Application</description> 
   <dependency>
     <dependentAssembly>
        <assemblyIdentity type="win32" 
             name="Microsoft.Windows.Common-Controls"
             version="6.0.0.0" 
             processorArchitecture="x86"
             publicKeyToken="6595b64144ccf1df"
             language="*" /> 
     </dependentAssembly> 
   </dependency>
   <file name="SftTree_IX86_U_70.ocx">
        <comClass description="SftTree/OCX Tree Control"
                  clsid="{10C7FF33-FC3E-4579-A9F2-C1BA410D3B56}"
                  threadingModel = "Apartment"
                  miscStatus="setclientsitefirst,simpleframe,alignable,activatewhenvisible,insideout,cantlinkinside,recomposeonresize"
                  progid="SftTreeOCX70.SftTree.1"
                  tlbid = "{10C7FF30-FC3E-4579-A9F2-C1BA410D3B56}"/>
        <typelib tlbid="{10C7FF30-FC3E-4579-A9F2-C1BA410D3B56}"
                  version="7.0" helpdir=""/>
   </file>
</assembly>

Testing a Setup Program

If you test the installation of your application's Setup program on a system where the development version of SftTree/OCX is installed, you may notice that you can no longer use SftTree/OCX in your development environment.  This is caused by the fact that your Setup program installed a "run-time only" control on your system, which has replaced the "design-time" or development version of SftTree/OCX.  You can reinstate (or re-register) the design-time version of SftTree/OCX by using the program entry “Maintenance, Register SftTree OCX in Windows Registry” in the SftTree OCX 7.0 program group.

Installing SftTree/OCX (for a Web Page)

When using SftTree/OCX on your web pages, only the file(s) shown below can be distributed royalty-free.  These files allow the use of the control on your web pages.  The design-time interface is not available to visitors of your web site.

Required Files

Important: Redistributable files are located in the SftTree/OCX installation directory (\Program Files\Softelvdm\SftTree OCX 7.0\Redist).

The following file is referenced by the OBJECT tag of a web page containing a SftTree/OCX control. This file must be available on your web server:

File Name

Description

SftTree_IX86_I_70.cab

Cabinet file containing the SftTree/OCX control, run-time only, compressed, with digital signature.

Version Control

Version control is insured by using the proper HTML OBJECT (see Using SftTree/OCX with Internet Explorer, CODEBASE keyword).  Maintenance releases and new versions of the product are fully upward compatible and are guaranteed to have a newer version number.  Make sure to check the file Readme.html which was installed with SftTree/OCX for the most current version number to use.


Feedback / comments / error reports for this topic
© 2015 - Softel vdm, Inc. - www.softelvdm.com